This document explains how to create stand-alone Macintosh applications using MacOberon. Since MacOberon's compiler is a fast and efficient 32-bit compiler that produces dense code, applications generated by MacOberon will often run faster and usually be smaller than similar programs developed using other programming environments.
Introduction
We assume that you know and appreciate the Oberon language and the MacOberon compiler already. So why not use them to develop standard Macintosh applications? In fact, MacOberon can be used to create such applications. The main concern here is how to gain access to the routines, types and constants of the Macintosh Toolbox.
The package of interface files distributed with this document contains the more important routines and types, and some constants of the Macintosh Toolbox. They are grouped in modules structured along the lines of the new Inside Macintosh series of books. Unfortunately, by the time this is released, not all of the new Inside Macintosh books are yet available, so that some stuff may still be in the wrong place. However, the interface files that we supply are plaintext source files and can be updated easily.
The Macintosh Toolbox
Using the Macintosh Toolbox from within MacOberon is slightly different from other programming environments such as MPW or Think Pascal. Most importantly, the data in MacOberon's interface files is structured similar to the new Inside Macintosh books (from now on IM). There are many toolbox calls that have changed their spelling in the new IMs, for example the routine that extracts a menu text used to be called GetItem and is now called GetMenuItemText. In most cases, we still use the old spelling, while in some cases both spellings are now implemented. (For example DisposPtr and DisposePtr )
Even more important is the treatment of register-based toolbox traps. Most of the memory manager routines and some of the file manager routines are register-based. In MacOberon, you won't be able to use these routines in the same way that you call stack-based ones. You will need to put your variables into the correct registers and read the results from the registers later. The relevant calling conventions can be found in IM under the assembly-language information that always follows the routine description. Example :
MPW Pascal : MacOberon :
myPtr:=NewPtr(theSize); SYSTEM.PUTREG(0,theSize);
ME.NewPtr;
SYSTEM.GETREG(8,myPtr);
At first sight, the Oberon version looks clumsy, but when looking at the produced object code, it is evident that MacOberon's output is much more efficient:
MPW Pascal : MacOberon :
CLR.L -(SP) MOVE.L theSize,D0
MOVE.L theSize,-(SP) _NewPtr
JSR xy MOVE.L A0,@myPtr
MOVE.L (SP)+,@myPtr
MOVEA.L (SP)+,A1
MOVE.L (SP)+,D0
_NewPtr
MOVE.L A0,(SP)
JMP (A1)
In MacOberon, you further need to precede all types and routines by their module name. It is convenient to use the alias import feature of Oberon to abbreviate the names of toolbox modules.
Here are all of the toolbox files supplied in this release, and possible abbreviations:
These toolbox files are not complete. For example, only a small amount of the constants have been declared. Therefore it will be necessary to add your own data to these files, or even better, create new toolbox files containing your additions, so you won't need to update all files when new versions of MacOberon are released.
You absolutly need the corresponding Inside Macintosh volumes when adding new routines, types or constants. It's also helpful if you can get hold of some Interface files of other development platforms as a starting base for creating MacOberon interface files. These files containing all data types and constants, and most routines. When implementing a new routine, just copy the hex code from the interface file. Don't forget the minus right after the PROCEDURE keyword, this tells the compiler that it is dealing with an interface procedure. It will substitute in-line the byte sequence appearing instead of a procedure body when compiling the procedure call. Example :
Trap only :
PROCEDURE- PaintRect*(r:Rect)
0A8H,0A2H;
Trap with routine selector :
PROCEDURE- CTabChanged*(port:GrafPtr)
020H,03CH,000H,004H,000H,007H,0ABH,01DH;
There are also some routines described in IM, that are not implemented as traps or traps with routine selectors. These are declared as [NOT IN ROM]. There is currently no official way to use these routines from MacOberon. Either you implement the functionality by yourself, or you disassemble the Interface library from another programming environment, such as Interface.o from MPW.
While implementing the toolbox files for MacOberon, simplifications were made to some data types. For example most of the types that are aliases of other simple types were left out. These are for example:
OSErr = INTEGER (also QDError)
Fixed = LONGINT
Size = LONGINT
SignedByte = SHORTINT
In some special cases, we also use LONGINT instead of MacMemory.Ptr to ease the use of the address.
The OSType in IM is declared as ARRAY [0..3] OF CHAR, however, this is nothing else than a LONGINT, so when using OSTypes you can pass a LONGINT, for example 'TEXT' = 54455854H. Two characters stand for the hex representation of the ASCII value of that character.
Another important difference is the byte-length of a character. Macintosh toolbox routines always use two bytes for a CHAR instead of one when using MacOberon. Therefore all toolbox routines using CHARs declare their CHARs as INTEGERs. Just pass ORD(myChar) to such routines where myChar is of Oberon type CHAR. Also remember that the function CHR() also returns a single byte CHAR type.
If you want to implement Macintosh datatypes using Ptrs or Handles, follow this scheme :
myDesc* = RECORD ... END;
myPtr* = POINTER- TO myDesc;
myHandle* = POINTER- TO RECORD p*:myPtr END;
The minus after POINTER hides this pointer from garbage collection. Therefore you will need to allocate and deallocate these pointers using NewPtr/DisposePtr, and won't be able to use the Oberon NEW procedure or the garbage collector for these pointers (which is sensible since Oberon cannot know automatically if the Toolbox is still using a pointer). When dereferencing the handle, just use myHandle.p.<myEntry>.
AppLinker
The Application Linker will create a stand_alone Macintosh Application from an Oberon object file. Using it is quite simple. There are, however, some rules to be observed. Because you are using the MacOberon Compiler, the applications produced need at least an 68020 processor. And if you are using REAL or LONGREAL within your application, FPU code is produced, so you have to check for the presence of an FPU by yourself. The check for an 68020 processor will be made by the bootloader when starting the created application.
If you want to use Oberon memory allocation and garbage collection, you also have to be sure that the application gets at least a 1MB memory partition for proper operation.
Usage of the AppLinker:
AppLinker.Link SampleApp [Creator]
To link an application, you need to provide the module name of your main module. If you specify a creator, the bundle bit will also be set.
To launch an application from within MacOberon for testing purposes, you can use :
AppLinker.Launch SampleApp
If there exists a file named SampleApp.res, then all resources from this file are copied to your application. For proper operation you have to include at least a SIZE resource id=-1 with the following flags set to one:
accept suspend/resume, activate on FG switch and can background
If this resource is not provided, some malfunctions may occur when switching between your and other applications.
The AppLinker also adds two code resources (id 0 and 1) containing the bootloader and two ALRT/DITL combinations (id 32766 / 32767) for the error messages and the trap handler. The object code is stored within the data fork of the application.
Oberon Features
The SYSTEM module contains some useful procedures, some of which are even required to develop Macintosh applications. Most of these procedures are translated into single machine instructions. Check the Oberon language report for more information about SYSTEM's procedures.
The most important procedures for Macintosh applications are:
SYSTEM.PUTREG(n,x) : Register n := x
SYSTEM.GETREG(n,v) : v := Register n
IF v is of a real type and 0<=n<=7, then floating point registers are used. Otherwise, 0<=n<=7 stands for data registers D0-D7, 8<=n<=15 for address registers A0-A7.
SYSTEM.PUT(a,x) : Mem[a] := x
SYSTEM.GET(a,v) : v := Mem[a]
SYSTEM.MOVE(s,d,n) : Mem[d]
Mem[d+n-1] := Mem[s]
Mem[s+n-1]
SYSTEM.VAL(T,x) : x interpreted as of type T
SYSTEM.ADR(v) : address of variable v (LONGINT)
Runtime Library
If you wish to retain the Oberon features of Garbage Collection and Run-Time Type Tests in your Macintosh-like applications, you need to link to an Oberon Runtime Library. Extract and compile the following module Runtime, or include the statements exactly as they appear here in every one of your main programs. Your application will need to call the Garbage Collector at regular intervals.
Runtime exceptions are generated to vector number 7 (TRAPcc), and array index check exceptions are compiled into the CHK instruction which has vector number 6. You can install a trap handler of your own in these slots. If you don't, MacsBug will handle the exception if installed. The TRAPcc.W instruction is used with a word parameter signifying the source of the trap as follows:
18 Type guard check (/t compiler option disables type-checking)
19 Implied type guard check in record assignment
23 Out of heap space (when Oberon's NEW is used, not NewPtr)
Use the /x compiler option to turn off array index range checking.
Examples
There are two examples containing Macintosh toolbox routines. The first one is a small standalone text editor using the built-in Macintosh TextEdit, that can be used as a framework for other applications.
Edit.Open SampleApp.Mod
The second one is an example of using the Oberon System and the Macintosh Interface together. It has only one command, Text, that uses a Macintosh file selector box to choose a plain text file and then opens a TextViewer containing the text from the file. You can use this command to import text files from other directories into MacOberon.
Edit.Open Import.Mod
Tips & Hints
Here is a list of usful hints that may not be so obvious to novice users:
- Use the brower '+' option if you are not sure how your data types are allocated. This is useful if you are implementing new Toolbox datatypes. You will be given the offsets of the record entries and therefore you can calculate the size of these entries. See the Brower.Tool for more information about the Browser.
- For string conversion between Oberon strings (null terminated) and Macintosh Pascal strings, you can use SetStr255 and GetStr255 from the MacToolbox module.
- When using CASE constructs, use the ELSE path for unwanted results. Otherwise traps may occur.
- When system error id=28 occurs, the application heap and the stack collided. Therefore, you have to increase the memory partition of your program or adjust the stack size. (See Inside Macintosh Memory for adjusting the stack size)
- If you are using REAL or LONGREAL operations, please don't forget to check for the presence of an FPU processor, otherwise your program just crashes on machines without an FPU (or an FPU emulator).
Further Reading
- Inside Macintosh Volume I, Chapter 4 (Assembly Language)
- Inside Macintosh Toolbox Essentials (for SampleApp )
- Oberon Guide (for Oberon System)
- Oberon Report (for Oberon programming)
Request for Comment
This is the second release of the ApplLinker. It seems to work fine, but the authors can assume no warranties. An advantage of the approach taken by MacOberon (BootLoader with link fixup) is that none of the usual restrictions of the Macintosh application architecture apply to applications created with the linker. For example, each module can have as much global data as required, and the code image can be of arbitrary size.
If you use this Linker, we would greatly appreciate your feedback to "franz@inf.ethz.ch".
(.txt)